org(-mode)

A lot is said online about org that confuses people unfamiliar with it. The best explanation I can give: Org is three things.

  1. A markup language. A weird flavour of markdown, if you like.

  2. Extremely good editor support inside emacs for that markup language. So good, that sometimes you are forgetting that it's just plain text.

  3. A bunch of software bundled with emacs that can parse this markup language, filter and re-order it to display it in a useful manner.

    4. I use org to keep myself organised (hence the name, I guess) and to plan my days. I put notes on various topics, todo lists, appointments, tracking of certain achievements, documentation on various things and more into org. I can then instruct org to automatically dig up all the appointments and generate an agenda for the day / week. Or I can instruct it to dig up all todo items with a certain tag from a certain section.

    Some people keep multiple files with cross-links (like how I have set up this digital garden!), however I prefer to have one single file, ~/Agenda/agenda.org. Inside I have a pretty boring hierarchy of topic headers. However I do make use of tags more liberally, for example I apply the :friends: tag to appointments that include my friends regardless in which section I have put them.

    Alternative implementations of org exist, but the one shipped with emacs is the only complete one. I am pondering how to procede with org if I couldn't use emacs anymore for some reason, because I prefer not to have a single point of failure for something this important. At least, since it's all plain text, I wouldn't loose the data!

    Tips & Tricks

    Emacs also contains the dirary package. It is intended to be a calendar for your appointments (and not a diary, what a confusing name). It has its own file where you can define appointments and it has its own agenda display, which even integrates with M-x calendar. The thing that makes it neat is that it supports displaying holidays, unlike org.

    By default, org and diary do not integrate, however you can manually enable that. You'll want to set org-agenda-include-diary to t. That way you can see appointments defined in the diary file and - more importantly - holidays in your org agenda.

    The other way around is possible as well: Just put %%(org-diary) in your diary file. This way appointments defined in org will show up in your diary daily agenda. I use this less often, but in theory M-x diary is quicker to open than the org agenda.

    If you have enabled the integration, you can even press c in your org agenda to jump to emacs calendar view, where you can press c again to jump to the org agenda view of the selected day.

    A Warning on Org Export

    Emacs org mode allows you to export org files. It can target different output formats, including HTML and PDF (via LaTeX). These are tempting to use, however ultimately they are of questionable quality.

    The HTML exporter that is shipped with org should not be used. It has many issues. The HTML it generates is not semantic and litters <div> everywhere. The IDs for its header links are generated randomly and as such change on every export. And you are sure to encounter other strange choices when you inspect the generated HTML. For this digital garden I created my own org HTML exporter. Luckily that is fairly trivial.

    The PDF / LaTeX export is somewhat fine for small documents, like a letter or note. However it quickly falls apart for anything serious, like writing papers or thesis. The problem is ultimately that org is presentational markup rather than semantic markup. Presentational markup is a no-go for any serious document. Org is simply not as expressive as LaTeX.